This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Preview URL: https://5fdb2675.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-841.preview.developers.cloudflare.com

Files with changes (up to 15)

looks good to me. @threepointone to go with the PR

/bonk review

Here's my review:

Review Summary

This PR correctly documents the security fix from cloudflare/agents#841, which eliminates an XSS vulnerability where error messages from external OAuth providers were interpolated directly into <script> tags via template literals.

Changes look good

1. oauth-mcp-client.mdx — The customHandler callback is simplified to no longer receive MCPClientOAuthResult. The old pattern of alert('Authorization failed: ${result.authError}') was the XSS vector. Now the handler just closes the popup unconditionally, and errors are surfaced through server.error in the connection state. The React examples are updated accordingly to display server.error when state === "failed".

2. mcp-client-api.mdx — The error field is added to the MCPServer type definition, and the failed state description now references it. The XSS safety note is clear and accurate.

Issue: Inconsistent customHandler example in mcp-client-api.mdx

The "Custom OAuth callback handling" example at src/content/docs/agents/model-context-protocol/mcp-client-api.mdx:210-218 still uses the old API pattern:

customHandler: (result) => {
    if (result.authSuccess) {
        return new Response("<script>window.close();</script>", {
            headers: { "content-type": "text/html" },
        });
    }
    return new Response("Auth failed", { status: 400 });
},

This is inconsistent with the updated examples in oauth-mcp-client.mdx, where customHandler no longer receives a result parameter. If the SDK change removed MCPClientOAuthResult from the callback signature, this example is now incorrect and should be updated to match the new pattern:

customHandler: () => {
    return new Response("<script>window.close();</script>", {
        headers: { "content-type": "text/html" },
    });
},

This should be fixed before merging to avoid documenting a broken API pattern in the reference page.

Minor note

The import type { MCPClientOAuthResult } from "agents/mcp" removal in the guide is correct — it's no longer used. But the MCP client API page never imported it explicitly in its examples, so no change needed there beyond fixing the customHandler signature.

github run

/bonk resolve merge conflicts and review

Summary

Merge Conflicts

No real merge conflicts on the two files changed by this PR. The branch has an "unrelated histories" issue with production (likely from how the sync bot created the branch), but the two commits since the last merge (ab4254b, a64f431) don't touch the same files as this PR.

Fixes Applied

Three issues were found and fixed in a single commit:

1. mcp-client-api.mdx:210-218 — customHandler example used the old API pattern (result) => { if (result.authSuccess) ... }. Updated to the new no-arg () => { ... } signature, matching the pattern in oauth-mcp-client.mdx. This was the issue flagged in the previous /bonk review.

2. mcp-client-api.mdx:373 — Client-side React example used server.connectionState which doesn't exist on the MCPServersState type. Fixed to server.state.

3. oauth-mcp-client.mdx:132,224 — Two React examples used useState without importing it. Added import { useState } from "react" to both code blocks.

Review Notes

• The core documentation changes (simplified customHandler, new error field, XSS safety notes) are correct and consistent
• The error: string | null field is properly documented in the MCPServersState type at mcp-client-api.mdx:480
• The XSS safety note at mcp-client-api.mdx:499 is accurate
• Minor nit (not fixed): useState<MCPServersState> initial values are missing resourceTemplates — this is a type completeness issue but wouldn't cause runtime errors and is common in doc examples

github run